docs(docs): restructure docs for the agent-platform pivot (v1.0 archive) - #5517
docs(docs): restructure docs for the agent-platform pivot (v1.0 archive)#5517mmabrouk wants to merge 17 commits into
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Archive the previous product's documentation as version 1.0 and refocus the current docs on the agent platform. - Add Docusaurus versioning: current docs are v2.0 and keep their URLs; the previous product (prompt management, evaluation, observability, custom workflows, concepts, integrations, tutorials, Python SDK reference) is frozen as v1.0 under /1.0/. A version pill next to the logo switches between them. - Redirect every old URL to its /1.0/ page so existing links and search results keep working. - Hide Tutorials and Integrations from the top navigation. - Regenerate the REST API reference from the production OpenAPI spec (adds the Mounts, Sessions, and Triggers endpoint groups). - Refocus the roadmap on agent-platform work; hide the GitHub discussions list behind a flag and keep the request-a-feature button. - Correct pages against the source: data retention, open source vs commercial, API rate limits, LLM providers, the testing / development-mode / formatting contributing guides. - Remove the video from the overview page and the outdated TypeScript FAQ. - Patch docusaurus-plugin-llms-txt to tolerate hidden and versioned sidebars.
d977e5a to
c44f26e
Compare
The patch hash in docs/pnpm-lock.yaml is written in pnpm 10's format (64-char hex). Vercel picks pnpm 9 for this project based on its creation date, and pnpm 9 expects the short base32 hash, so the frozen install aborts with ERR_PNPM_LOCKFILE_CONFIG_MISMATCH. package.json already declares packageManager pnpm@10.30.0. Invoke pnpm through npx rather than installing it globally: Vercel's pre-installed pnpm 9 shadows a globally installed binary on PATH, so 'npm i -g pnpm@10.30.0' runs but the wrong pnpm still executes.
8a41fdb to
0211fbd
Compare
Adds the documentation for the agent product: a Learn path, concept pages, problem-shaped guides, and a developer reference. Sidebar: Getting Started, Learn, Concepts, Guides, Contributing, Misc. Developer reference goes in the existing Reference section in the top bar rather than the docs sidebar. - Getting started (2): what Agenta is, with the launch video, and a quick start that no longer teaches the previous product. - Learn (2): build your first agent, and build a marketing coworker that ends up running on a schedule. - Concepts (9): agents, skills, tools, files, permissions, automations, harnesses and models, sessions and versions, cost and usage. - Guides (11): instructions, permissions, skills, MCP servers, knowledge folders, automations, harness and model, subscriptions, cost. - Reference (4): agent configuration, invoke, batch runs, chat message format, each field traced to the code it comes from. Every UI label was taken from the running product rather than written from memory. Where the product does not do something, the page says so: there is no batch endpoint, no skills catalog, and no per-field version history, so the docs point at the Registry instead. 52 screenshots plus two hand-written SVG diagrams, which avoids adding a Mermaid dependency and another lockfile change.
| description: "An agent in Agenta is a configuration you build for one job, run by a harness and a model. Its instructions are sent at the start of every session." | ||
| --- | ||
|
|
||
| An agent in Agenta is built for one job. This page covers what an agent is made of, how its instructions work, and why one shared context window shapes every other choice. |
There was a problem hiding this comment.
built for one job does not make sense. let's remove it. instead provide context of what you are going to talk about. keep it simple. This page covers what an agent is made of, how its instruction works, and when to use or something like that
There was a problem hiding this comment.
Done. The page now opens with one plain context sentence: what an agent is, then what the page covers.
|
|
||
| An agent in Agenta is built for one job. This page covers what an agent is made of, how its instructions work, and why one shared context window shapes every other choice. | ||
|
|
||
| {/* VIDEO: An agent with empty instructions answering a work question badly, then the same agent after its instructions describe the company and the job, answering it well. */} |
There was a problem hiding this comment.
Removed, along with every other video comment across the docs.
|
|
||
| {/* VIDEO: An agent with empty instructions answering a work question badly, then the same agent after its instructions describe the company and the job, answering it well. */} | ||
|
|
||
| ## An agent you build, not one you are given |
There was a problem hiding this comment.
let's not use cryptic pinyin substitles. Reading a subtitle should tell me clearly what the paragraph says. this does not. get a subagent to go over all the documentation and check each and every subtitle and title and change them to something meaningful.
however this whole section does not make any sense. The chatgpt comparision should be used to clarify the argument not to build it. What way we should say it: the question is, what other questions? Why would you want to use agents? I think you start by saying, "Agents are used for custom agents. You create a custom agent for a certain task or job, and then you provide examples, say a marketing agent or an agent that is with your SEO."
It could be:
- General, like a general marketing agent.
- More specific, like an agent that is with your SEO.
- More of an automation, where an agent just reports about your competition.
It depends on how you structure it. That's kind of the first thing, and then you do a comparison. I say, "If you used ChatGPT, etc., the agents are kind of pre-built general agents. They work with everything." I say, "However, an agent is specific. It has instructions, and it allows you to do specific things. You can improve them over time by changing the instructions and making them work the way you want them to."
The first decision is to get what the agent does, and then you explain that that's one paragraph, one thing: the idea here is when to use an agent. That's kind of the main idea.
Then we have a couple of things, and you see them:
- What is an agent made of?
- What is an agent?
- What are the compositions of an agent?
You relate it to the thing. Before, you just explained: here are examples of agents. You said what the agent is made of, and then you connect these two examples to the things that you said in the beginning. Then you have how to create an agent, and you say: "Okay, you can create an agent by talking to it, or you can create an agent by configuring it yourself."
Then we have a section about versioning because we said how to create an agent. There is a part about how to create an agent. I say: "Okay, when you chat with an agent, it has access to tools in the playground that allow it to change its own configuration. That configuration is versioned, which means that when you provide an example to the main thing again, if it made a mistake, let's say your SEO thing, then you can tell it. It will change so that it improves over time." This would be kind of change management or improvement.
There was a problem hiding this comment.
Rebuilt the page on this outline. "When to use an agent" opens with three concrete examples (a general marketing agent, an SEO-specific agent, a competitor-watch automation) and the ChatGPT comparison follows to sharpen the difference instead of carrying it. Then "What an agent is made of" (short, links out), "How to create an agent" (chat with it, or configure it), and "Agents are versioned and improve over time". A subagent also swept every title and subtitle in all sections and renamed the cryptic ones to statements of what the section says.
|
|
||
| They are part of the agent rather than something you attach to it. An agent with no instructions is a general assistant. The instructions are what make it yours. | ||
|
|
||
| ### What goes in them |
There was a problem hiding this comment.
Start the first section with clear examples, and then follow these examples all around so the concepts are connected to something.
There was a problem hiding this comment.
The three examples now open the page and return in the made-of list and in the versioning section (the SEO agent pulling numbers from the wrong report).
|
|
||
| So context that has to be present every time goes in the instructions. Reference material the agent can look up when the moment comes goes in a file. See [Files and knowledge](/concepts/files-and-knowledge). | ||
|
|
||
| ### Instructions are resent on every turn |
There was a problem hiding this comment.
Again, the header should explain something. A paragraph should be about one thing, and the header should explain something. You're going into kind of specificities about the context and how to use them, but that's not the concept itself.
There was a problem hiding this comment.
This material moved off the page. The every-turn cost and the context handling now live on the new Instructions concept page, and the headers there state what each section says.
|
|
||
| That is the tension. More context makes the agent better at the job, and it also makes every turn more expensive and leaves less of the context window for the work itself. The consequence is that instructions hold what must be present every turn, and everything else lives in a skill or a file. | ||
|
|
||
| ### How instructions grow |
There was a problem hiding this comment.
All of this, like how instructions grow, and the fact that instructions should go first into a concept about instructions.md, while we keep here the general stuff about the agent.
When we say what the agent is made of, we say:
- the instruction
- the tools
- whatever
For each one, we have a short description of the thing. Instead of trying to explain what goes into them and going deep there, just provide the general idea in this thing, right?
For the details about harness, models, and version, we can go much more into detail here. This is the high-level idea about the agent, like: - how to create them
- how to change them
- the fact that they are versioned
- when to use them
For each one of these, there is a link to go into more detail. I think that's the way you should go on this page.
There was a problem hiding this comment.
Done as described: there is now a concept page at /concepts/instructions holding what goes in the instructions, the every-turn cost, the shared context window, and how instructions grow. The agents page keeps one short description per part with a link to each part's page.
|
|
||
| A skill teaches an agent how to do one kind of task. This page covers what a skill contains, why it is loaded differently from the instructions, and what makes a skill fire at the right moment. | ||
|
|
||
| {/* VIDEO: An agent asked for a PDF report. It names the skill it is loading, reads the skill, and follows the steps in it to produce the file. */} |
There was a problem hiding this comment.
rm. please remove these comments about videos from everywhere
There was a problem hiding this comment.
All 23 video comments are removed across the docs.
|
|
||
| A skill is a recipe, or a short handbook, for one kind of thing the agent does. How to write a PDF. How to run a particular analysis. How to open a pull request the way your team does. | ||
|
|
||
| It is written as text, the same as the instructions. The difference is not the content. It is when the agent reads it. |
There was a problem hiding this comment.
Ok, this is just badly written. I want you to learn and memorize this because I want you to spin over them in a sub-agent. First, try to understand the lesson from this, then spin over a sub-agent that reviews all the documentation so that this kind of sentence changes results.
I'm going to explain to you how I tried to fix it.
First thing: if it's a concept page, I need to try to understand the different concepts, things, and modules we want to explain. We have the paragraph "What this skill is." The expected thing is that it would understand 90% of the points from this "What this skill is." When I ask what the skill is, how do I look at it?
- I want to understand what is in this skill.
- Where should I use it? What's the motivation behind it?
You do the first thing: you say, "A skill is a recipe or a short handbook for one kind of thing the agent does." That's very badly written, right? Kind of break down the ideas: a skill recipe or a short handbook that is provided to the agent so that it knows how to solve this.
Then you jump: "How to write PDFs?" Explain things. Go with the flow! In this case, say, "Examples of skills are a skill to write a PDF." Then you go and say, "Okay, what is in this skill?" Then you say, "Okay, skill." There is skill.mt, which includes a title, a short description, and then the content, and it has also resources that help.
Then you go back and explain the original thing. For example, a write-a-pdf skill would have this, this, this. For example, it would have a description and say, "Okay, use this when you write a PDF." How to do it? There may be a resources description that helps with this.
Then I would go, "Okay, why use a skill?" Because you say, "Skills are preloaded." Actually, the reason is: why do you use a skill? Skills are very similar to instructions, and see what I said before or later here in this text. The first thing is, "Okay, this is where the users come in. Skills are very similar to instructions they provide this." However, the difference is that, actually, the way to do it is: skills are very similar to instructions. However, in contrast to instructions, skills are not sent every startup session. Only the description of the skill is sent at the beginning of the discussion, right?
Then you go and explain this more, right? Both provide this, however, and then you explain kind of why this matters. Structure it well. Now, having a paragraph called "A description decides whether a skill is bad," because again, that's not it. There is a paragraph that simply explains the fact that the advantage of skills is that they are not preloaded. Then I would say, "When to use skills and when to use instructions." Basically, build upon that. You see where "How to create skills" is not where skills come from. It's really very badly written, and the skill instruction or file is redundant. Why do you have that?
So we are here in the paragraph that explains the skill. First, since this is a concept page, let's start by adding more detail about what is in the skill. The skill has a skill.md which include a title, a short description of the skill, and hten content.
e.g. Skills are very similar to instructions but differ on one axis. Both skills and instructions provide context/instruction to the agent on how to solve the task. Additionally, both are injected at some point in the prompt sent to the LLM. The difference lies when these are injected. Instructions are injected ... While skills are only partially injected (the description). Only when the .. is the rest injected....
<another sentence now that summarizes the paragraph of
Instructions are send fully at the start of every session, while skills are not.
Instead
There was a problem hiding this comment.
Rewrote the page on this structure. "What a skill is" now explains what is in a skill (a folder with SKILL.md holding a name, a short description, and the content, plus supporting files) and grounds everything in a PDF-report example the page keeps returning to. The comparison section opens with "Skills are very similar to instructions" and makes the one difference explicit: when they are injected. Instructions go in full at session start; a skill contributes only its name and description until the agent loads the body. A "When to use a skill and when to use instructions" section builds on that. A subagent then applied the same lesson (one idea per paragraph, opening summary sentence) to every page.
|
|
||
| [Manage skills](/guides/manage-skills) covers adding, writing, and removing them. | ||
|
|
||
| ## Skill, instruction, or file |
|
|
||
| The rest of the skill can be as long as it needs to be. | ||
|
|
||
| ## Where skills come from |
There was a problem hiding this comment.
break into how to create skills. and then break writing your own. then link to the page manage skills that should explain
- how to create skills manually
- how to upload skills (drag and drop a folder)
where to find skills.
- add links for places where you find them .
- then add notes (please structure better)
There was a problem hiding this comment.
Split as asked: "How to create skills" covers writing your own and links Manage skills, which now leads with the two routes (write in the New skill dialog, or upload by dropping a folder). "Where to find skills" links Anthropic's skills repository and a community collection, with the read-before-use caveat as a note admonition.
|
🤖 The AI agent says: Added two isolated Codex comparison drafts in commit 0ec75a1:
Both drafts use descriptive headings, keep procedures in guides, contain no video placeholders, and were verified with a successful Docusaurus production build. |
…raphs, instructions concept page
|
🤖 The AI agent says: The revised Codex Agents concept is ready for review in commit This pass replaces the component-first explanation with one marketing launch agent that develops across the page. It removes the ChatGPT comparison, reduces runtime detail, and explains creation and versioning through concrete moments in the same story. The Docusaurus production build passes. |
|
🤖 The AI agent says: The Codex Instructions comparison page is ready in commit It starts with the context a launch agent should always know, uses a small real instruction example, then explains what belongs in instructions versus skills and files. Context-window and per-turn cost mechanics are left out of the concept page; the page ends with a concrete before-and-after correction. The Docusaurus production build passes. |
|
🤖 The AI agent says: The Codex Tools and integrations comparison page is ready in commit It starts with the launch work the tools make possible, then explains action-sized tools, built-in integrations, referenced workflows, and MCP through that same job. Harness loops and token-cost arguments are removed; focused tool choice and permissions stay reader-facing. The Docusaurus production build passes. |
|
🤖 The AI agent says: The Codex Files and knowledge comparison page is ready in commit It explains session files as today's desk and agent files as the shared shelf, then shows how an approved launch email becomes reusable knowledge. It avoids absolute cost claims and keeps folder-level instructions and on-demand reading in plain language. The Docusaurus production build passes. |
|
🤖 The AI agent says: The Codex Permissions comparison page is ready in commit It begins with the practical difference between reading analytics and posting a report, then introduces allow, ask, and deny. The approval sequence is explicit, chat and automation needs are separated, and the page no longer implies that instructions enforce permissions. The Docusaurus production build passes. |
|
🤖 The AI agent says: The Codex Automations comparison page is ready in commit It frames automation as the same agent started another way, then follows one Monday campaign report through schedules, events, complete starting context, permissions, delivery, shared files, and pinned versions. Setup mechanics remain in the three guides. The Docusaurus production build passes. |
|
🤖 The AI agent says: The Codex Harnesses and models comparison page is ready in commit It separates the model, harness, and credential through the same Monday campaign report, then explains when each choice changes. Provider inventories and implementation diagrams are removed; compatibility caveats and links to the selection and subscription guides remain. The Docusaurus production build passes. |
|
🤖 The AI agent says: The Codex Sessions and versions comparison page is ready in commit It uses the Monday and Tuesday campaign-report example to separate conversation history from the agent setup that carries forward. It also removes the absolute memory claim, explains shared agent files in plain language, and connects session evidence to configuration history in the Registry. The Docusaurus production build passes. |
|
🤖 The AI agent says: The Codex Cost and usage comparison page is ready in commit It follows one campaign-report request through several model and tool steps, explains why longer work usually carries more context, and distinguishes Agenta estimated cost from the provider bill. The optimization advice now serves clarity first instead of reading like token accounting. The Docusaurus production build passes. |
|
🤖 The AI agent says: The complete Codex concept-page comparison set is now ready. Each page was built, committed, pushed, and posted separately for review:
The final collection-level pass found all ten pages present with consistent frontmatter, the recurring marketing-launch example, reader-facing headings, and none of the absolute or overly technical phrases called out in review. The Docusaurus production build passes. Local and remote lane SHAs both resolve to |
|
🤖 The AI agent says: The introduction cleanup is ready in commit The opening keeps Mahmoud’s AI coworkers / AI automations framing. I shortened the sentences, restored the conversational energy of his draft, fixed the grammar and typos, and kept the concrete GTM, HR, competitor-report, sales-follow-up, and signup examples. The Docusaurus production build passes. |
1 participant
What this does
Restructures the documentation for the pivot to an agent platform, and writes the documentation for the agent product itself.
Before this, the front door contradicted the product. The introduction opened with the agent positioning and then spent the rest of the page on prompt management, evaluation, and observability. The quick start was entirely the previous product: create a prompt, build a test set, run an evaluation, deploy a prompt, fetch it from the SDK. A reader was told Agenta is a workspace for agents and was then taught to manage prompts.
The version split
/1.0/. A version pill next to the logo switches between them, and v1.0 pages carry a "no longer maintained" banner.createRedirectsrule forwards every old URL to its/1.0/page, so old links and search results keep working.The new documentation
28 pages. The sidebar reads Getting Started, Learn, Concepts, Guides, Contributing, Misc. Developer reference goes in the existing Reference section in the top bar, not in the docs sidebar.
Illustrated with 52 screenshots taken from the running product, plus two hand-written SVG diagrams. The diagrams are SVG rather than Mermaid so this does not add a dependency or change the lockfile.
Accuracy
Every UI label came from walking the product, not from memory. Where the product does not do something, the page says so rather than describing a feature that does not exist:
AGENTS.mdexists. The add-instruction-file control is disabled.Two factual bugs were caught and fixed during review, both verified against the code: the read-only permission default asks for writes rather than blocking them (
sdk/utils/types.py,services/runner/src/permission-plan.ts), and permissions are two separate layers with different option names rather than one.The reference pages trace every field and payload to the file and symbol it came from.
Corrected against the source code
Each of these was verified against the code, not the old page: data retention overstated retention by up to four times and used a plan name that does not exist; open source vs commercial had role-based access control in the wrong column and was missing audit logs; API rate limits had wrong numbers and stale endpoints; the built-in LLM provider list was wrong; and the contributing guides had dead install commands and a moved SDK path.
REST API reference
Regenerated from the production OpenAPI spec. It grows from 410 to 512 endpoints and adds the Mounts, Sessions, and Triggers groups. This is the bulk of the file count.
Build
docs/vercel.jsonpins pnpm 10 for the install step. The patch hash indocs/pnpm-lock.yamlis written in pnpm 10's format, Vercel selects pnpm 9 for this project, and pnpm 9 rejects that hash. pnpm is invoked throughnpxbecause Vercel's pre-installed pnpm 9 shadows a globally installed one.The docs build passes with
onBrokenLinks: throw, so every internal link resolves.Still open
{/* VIDEO: ... */}comment describing the short video that belongs there. Only the launch video is real so far./evaluation/quick-start-uiand/observability/overvieweach get two targets, and two redirects would override existing pages.